Skip to content

fix(sdk-coin-eth): enforce strict ERC-7984 delegation verification on test/staging (CECHO-2720) - #10191

Merged
nvrakesh06 merged 1 commit into
masterfrom
nvrakeshreddy/cecho-2720-bitgojs
Nov 18, 2026
Merged

nvrakesh06 merged 1 commit into
masterfrom
nvrakeshreddy/cecho-2720-bitgojs

Conversation

@nvrakesh06

Copy link
Copy Markdown
Contributor

Description

Fixes the client-side verification gap from CECHO-2720: Erc7984Token.verifyEnableTokenTransaction validated only the token contract addresses inside an enable-token prebuild and ignored every other security-relevant field of the delegation calldata, allowing a compromised platform to substitute the decryption delegate, smuggle extra ACL calls inside the multicall, or wrap a theft prebuild in callFromParent.

What this PR does (env-gated on bitgo.env === 'test' || 'staging'; prod keeps legacy behavior for one release cycle):

  1. Fail-closed decoder (feat(abstract-eth)): new decodeDelegationCallsFromCalldata surfaces per-call delegate/expiry and callFromParent target/value, and rejects any inner multicall entry that is not a well-formed delegateForUserDecryption call (unknown selector or trailing bytes). The legacy decodeTokenAddressesFromDelegationCalldata is untouched.
  2. Strict verifier (fix(sdk-coin-eth)): on test/staging, verifyEnableTokenTransaction now requires exact token-set match against the requested tokens, a single consistent delegate, a future expiry, and for the forwarder shape callFromParent target == ACL contract with zero native value — which blocks the forwarder fund-exfiltration prebuild from the ticket. The txJson.to wallet-owned-forwarder check is not statically verifiable client-side; the on-chain onlyParent modifier plus the enforced target/value checks close the theft vector regardless of the forwarder addressed.
  3. Delegate identity pin (fix(statics)): new optional EthereumNetwork.zamaViewingKeyAddress. When pinned, the verifier rejects any delegation whose delegate is not the BitGo enterprise viewing key. ⚠️ Needs real values from the Coins Echo team (prod mainnet + Hoodi testnet) — until pinned, strict mode enforces everything else and the identity check is dormant. Statics networks are frozen at runtime, so the pin is a tamper-proof trust anchor against a compromised platform.

Rollout plan (tracked in CECHO-2720): this is Release N — strict checks on test/staging only, prod unchanged (no prod rollback concern: prod behavior in this release is identical to current). After staging/testnet validation of real enable-token flows (both delegation shapes, TSS and rebuild signing), Release N+1 removes the env gate and enforces everywhere, published as a minor bump. The ticket must not be closed after Release N alone.

Issue Number

CECHO-2720

Type of change

  • Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

Unit tests — 15 new cases in modules/sdk-coin-eth/test/unit/erc7984Token.ts:

  • delegate substitution rejected when the network pins a viewing key; matching delegate accepted
  • inconsistent delegates across inner calls rejected
  • smuggled non-delegation inner call (ACL.approve) rejected
  • forwarder theft prebuild (callFromParent(attackerContract, forwarderBalance, multicall)) rejected
  • callFromParent with non-zero native value rejected
  • extra unrequested delegation calls rejected; expired delegations rejected
  • strict checks fire on staging env as well as test
  • prod gate proof: the theft prebuild and the smuggled-call prebuild both still verify on env === 'prod' (legacy path), demonstrating the gate works in both directions
  • decoder unit tests: full record decode from multicall, callFromParent target/value, unknown-selector throw, trailing-bytes throw

Full-module runs: modules/sdk-coin-eth 574 passing, modules/abstract-eth 188 passing, modules/statics 42,051 passing — zero failures.

Reproduce: cd modules/sdk-coin-eth && npx mocha (also modules/abstract-eth, modules/statics).

Remaining pre-GA work (per the ticket): exercise real enable-token flows against staging/testnet in strict mode before Release N+1 removes the gate.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • My code compiles correctly for both Node and Browser environments
  • I have commented my code, particularly in hard-to-understand areas
  • My commits follow Conventional Commits and I have properly described any BREAKING CHANGES
  • The ticket or github issue was included in the commit message as a reference
  • I have made corresponding changes to the documentation and on any new/updated functions and/or methods - jsdoc
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

@linear-code

linear-code Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

CECHO-2720

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

⚠️ Compatibility checks are failing on Node.js 27-nightly (experimental, non-blocking). This does not block merge, but it signals an incompatibility to fix before this release becomes supported.

View run

@nvrakesh06

Copy link
Copy Markdown
Contributor Author

@claude review

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @nvrakesh06's task in 27s —— View job


Review of PR #10191 (CECHO-2720 strict ERC-7984 delegation verification)

I read the diff of the three source files (zamaUtils.ts, erc7984Token.ts, networks.ts). I did not run the tests or read the test file in detail. The design is sound: the decoder fails closed, the strict checks cover the attack shapes in the ticket, and the env gate is simple. The findings below are mostly minor, except the first one.

Main concern

  1. The delegate pin does nothing until real addresses are set. zamaViewingKeyAddress is declared in networks.ts, but no network sets it. Until it is set, a compromised platform can still substitute any delegate as long as all the delegates match each other. That is the core threat in the ticket. The PR description says this, but I'd treat the pin as a blocker for closing CECHO-2720. I'd also add a TODO next to the verifier, or a test that fails once the address is set but not enforced, so the dormant check isn't forgotten before Release N+1.

Correctness and robustness

  1. Duplicate or extra tokens are only caught by the length check. erc7984Token.ts:~900 checks that each requested token appears in the decoded set, then checks calls.length === requestedAddresses.length. A request for [A, B] with calldata [A, A] fails on the first check, which is fine. A request for [A, A] with calldata [A, A] passes, and that is arguably correct. A request for [A, B] with calldata [A, B, B] fails on length, also fine. Comparing the two as sets plus a length check would state the intent more clearly. As written, though, I found no bypass.

  2. Expiry check has no upper bound. The strict check only requires expiry > now. A compromised platform could set an effectively infinite expiry (for example uint48.max), and the viewing-key delegate would then keep decryption rights indefinitely. If the Coins Echo team has an expected maximum, such as the default duration used by DecryptionDelegationBuilder, enforcing it would tighten this. If not, please note in the code that this is deliberate.

  3. Clock dependence. Date.now() is compared against the on-chain expiry. A client with a badly skewed clock will see false rejections, but only on test and staging for now. This is acceptable, but worth knowing before the gate is lifted in N+1.

  4. Double decode and a gap between the two paths. The legacy decodeTokenAddressesFromDelegationCalldata runs first, then decodeDelegationCallsFromCalldata runs on the same data. That is fine for the rollout. When the gate is removed, delete the legacy call so the two decoders can't drift apart.

  5. Inner call length check. innerHex.length !== 8 + 3 * 64 is correct for delegateForUserDecryption(address,address,uint64), but it assumes a static 3-word layout. The decoder's types are delegateForUserDecryptionTypes. If those types ever change, the magic number has to change with them, so I'd derive it from the type list or add a comment.

  6. callFromParent target check, but no check on txJson.to. The PR explains why to can't be verified statically, and I agree that the onlyParent modifier plus target and value checks close the theft vector. One more hardening option is to check txJson.to against the wallet's known forwarder addresses when they are available in txParams or walletData. That would also block a prebuild sent to a different wallet-owned forwarder. I wouldn't hold the PR for it.

Style and docs

  1. Misplaced JSDoc in zamaUtils.ts (~L548). The doc block that begins "Full, fail-closed decode of an ERC-7984 delegation calldata" sits above the DecodedDelegation interface instead of above decodeDelegationCallsFromCalldata. The function then has a second, shorter doc block. The DecodedDelegation interface ends up with the function's description. Please move the long description to the function and give the interface a one-line comment.

  2. Error messages for the same condition differ between the decoder and the verifier. For example, Not a valid delegation calldata has no verifyEnableTokenTransaction: prefix. That is harmless but inconsistent with the rest of the file.

  3. Check that decodeDelegationCallsFromCalldata is exported from the package index. The import in erc7984Token.ts comes from @bitgo/abstract-eth, and the other decoders go through zamaUtils re-exports. The PR's tests passing suggests it is, but I haven't confirmed the build.

Tests

The 15 new cases cover the key scenarios, including the prod gate in both directions. Two cases I'd add:

  • Mixed-case delegate or token addresses in the calldata, since the decoder lowercases them.
  • A callFromParent whose inner multicall is empty (calls.length === 0). This should be rejected by the delegates-size check, but a test would pin that behavior.

Rollout

Release N is env-gated and prod behavior is unchanged, so the risk of merging is low. Because the delegate pin is the strongest control and it is dormant, please keep CECHO-2720 open until the real addresses are pinned and N+1 removes the gate.

I made no code changes.
· branch nvrakeshreddy/cecho-2720-bitgojs

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Comment thread modules/statics/src/networks.ts Resolved
… test/staging (CECHO-2720)

Adds a fail-closed strict verification tier for ERC-7984 enable-token
prebuilds, enforced when bitgo.env is test or staging; prod keeps legacy
behavior for one release cycle (the env gate is removed in Release N+1,
tracked in CECHO-2720).

- abstract-eth: new decodeDelegationCallsFromCalldata surfaces the
  delegate and expiry of every inner delegateForUserDecryption call
  and the callFromParent target/value, and fails closed on any inner
  multicall entry that is not a well-formed delegation call (no
  smuggled calls). The legacy decoder is unchanged.
- sdk-coin-eth: verifyEnableTokenTransaction strict mode requires an
  exact deduplicated token-set match, a single consistent delegate
  equal to the pinned enterprise viewing key (fail closed when no pin
  exists), a future expiry, and callFromParent target == ACL contract
  with zero native value (blocks forwarder fund exfiltration).
- statics: optional EthereumNetwork.zamaViewingKeyAddress pins the
  BitGo enterprise viewing key per network; the real values for
  mainnet and Hoodi are a hard prerequisite for Release N.

Addresses the Claude review findings on PR #10191: fail-closed without
a pinned viewing key, and set-based token matching so duplicate
requested tokens cannot smuggle unrequested tokens. The multisig
enable-token path is a pre-existing gap tracked separately as
CECHO-2815.
@nvrakesh06
nvrakesh06 force-pushed the nvrakeshreddy/cecho-2720-bitgojs branch from 787d426 to fe6c02f Compare November 17, 2026 11:31
@nvrakesh06
nvrakesh06 marked this pull request as ready for review November 17, 2026 11:38
@nvrakesh06
nvrakesh06 requested a review from a team as a code owner November 17, 2026 11:38

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@nvrakesh06

Copy link
Copy Markdown
Contributor Author

Two findings from the claude review on the stacked #10192 (CECHO-2719) apply to this PR's code, not 2719 — flagging here so they land with the commits that introduced them:

  1. 🟡 verifyStrictEnableTokenCalldata exact-token-set check can be bypassed with duplicate enableTokens entries: requestedAddresses is not deduplicated, so enableTokens: [A, A] against a decoded delegation set [A, B] passes both the subset check and the count check — the wallet would grant decryption rights over token B it never requested. Fix: dedupe requestedAddresses (or reject duplicates) and require every decoded token to be in the requested set with no decoded duplicates.
  2. (nit) The decodeDelegationCallsFromCalldata JSDoc block starting "Full, fail-closed decode…" sits above interface DecodedDelegation instead of the function.

The zamaViewingKeyAddress dormancy is already tracked in the ticket/PR description (needs the real values from the Coins Echo team).

@nvrakesh06
nvrakesh06 merged commit bc1f62d into master Nov 18, 2026
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants